home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 November / Macworld (1999-11).dmg / Updaters / WhiteCap 3.0.4 / WhiteCap Source.sit / WhiteCap Source / Headers / MacAMP_Visual.h next >
Text File  |  1999-07-13  |  13KB  |  348 lines
  1. /*
  2.     Visual Plug-in API
  3.     ©1999, @soft
  4.     
  5.     Description:    The plugin API for MacAMP visual plugins (windowed
  6.                     and full-screen).
  7.     Version:        1.2
  8.     Released:        7/11/99
  9.     Compatibility:    MacAMP 1.0
  10.     Version history:
  11.     
  12.      Date    Who        Changes
  13.     ------+------+------------------------------------------------------
  14.     071199    SKA        Changed a few callbacks, commented the file a little
  15.                     better.
  16.     070899    SKA        Added two new hooks for plugins. 
  17.                     All visual plugins has to be recompiled.
  18.     061999    SKA        Added GetSoundBuffer hook for direct access to sound
  19.                     data
  20.     050299    SKA        Initial release
  21.     043099    SKA        Started the work
  22.  
  23.     SKA = Slava Karpenko
  24. */
  25.  
  26. #pragma once
  27.  
  28. #include <Errors.h>
  29. #include <Files.h>
  30. #include <MacTypes.h>
  31.  
  32. #ifdef __cplusplus
  33. extern "C" {
  34. #endif
  35.  
  36.  
  37. /************************************************************
  38.                     ENUMS AND CONSTANTS
  39. ************************************************************/
  40. #define VP_API_VERSION                0x0120
  41. #define plugVisual                    'VIS!'
  42.  
  43. // Flags for VisInfoBlock.flags
  44. enum {
  45.     vpFlagStartOnLaunch            = 0x0001,        // The plugin will be started on application launch time
  46.     vpFlagHideInMenu            = 0x0002,        // The plugin will not be shown in menu
  47.     
  48.     vpFlagStartOnLaunchMask        = (1L << 0),
  49.     vpFlagHideInMenuMask        = (1L << 1)
  50. };
  51.  
  52. // useful macros to quickly set headers/footers of VPInfoBlock
  53. #define VP_INFOBLOCK_HEADER(a,b) VP_API_VERSION, plugVisual, a, b, nil
  54. #define VP_INFOBLOCK_HEADER_WITH_FLAGS(a,b,c) VP_API_VERSION, plugVisual, a, b, c
  55. #define VP_INFOBLOCK_FOOTER    nil,nil,nil,nil,nil
  56.  
  57. /************************************************************
  58.                     ERRORS & RETURN VALUES
  59. ************************************************************/
  60. enum {
  61.     // Plugin return codes
  62.     errVisNoErr            = noErr,
  63.     errVisTerminate    = 666,            // terminate the plugin
  64.     errVisNoMemory,                    // terminate the plugin and display no memory alert
  65.     
  66.     errVisCustom                    // MacAMP will call VisError function and terminate your
  67.                                     //  plugin if you request to.
  68. };
  69.  
  70. /************************************************************
  71.                     FUNCTION DEFINITIONS
  72. ************************************************************/
  73. // Called when the plugin is initialized. You get the FSSpec to the plugin file
  74. // (for opening resfork if you need to). You shall return WindowPtr to your plugin (if you create any).
  75. extern OSStatus    VisInitialize(FSSpecPtr inPlugin, WindowPtr* outWindow, UInt32* ioRefcon);
  76.  
  77. // Called on termination. Plugin should dispose all buffers/structures it had and prepare
  78. // the mind for ethernity. Disposing window is your plugin's responsibility as well.
  79. extern OSStatus    VisTerminate(WindowPtr inWindow, UInt32* ioRefcon);
  80.  
  81. // Called whenever MacAMP has some free time. If you're a full-screen plugin, you get this event more often.
  82. extern OSStatus    VisIdle(WindowPtr inWindow, UInt32* ioRefcon);
  83.  
  84. // Display About box or do some about graphic in the plugin window.
  85. extern OSStatus    VisAbout(WindowPtr inWindow, UInt32* ioRefcon);
  86.  
  87. // Draw whatever you want to. Called periodically to ensure steady effect flow.
  88. extern OSStatus VisDraw(WindowPtr inWindow, UInt32* ioRefcon);
  89.  
  90. // This function is called when user clicks in window that is controlled by your plugin.
  91. // You can do what you want with that click.
  92. extern OSStatus VisClick(WindowPtr inWindow, Point inClick, UInt32* ioRefcon);
  93.  
  94. // This function is called when user presses a key. Note that MacAMP gets this key as well
  95. // as all other visual plugins.
  96. extern OSStatus VisKeyDown(WindowPtr inWindow, EventRecord* inEvent, UInt32* ioRefcon);
  97.  
  98. // This function is called when window-specific event is posted for your visual plugin.
  99. // If you have this set, it can override VisDraw function, and it is called when MacAMP
  100. // wants your plugin to redraw.
  101. extern OSStatus VisMacEvent(WindowPtr inWindow, EventRecord* inEvent, UInt32* ioRefcon);
  102.  
  103. // This function called if you return errVisCustom. You should copy the error string
  104. // and errNum (optionally) and return whether the error is fatal or not. If this function
  105. // returns true, MacAMP terminates your plugin, otherwise continues execution.
  106. extern Boolean VisError(StringPtr outErrString, OSStatus* outErrNum);
  107.  
  108. // If you define this function in your gPlugInfo, MacAMP will add a corresponding item into
  109. // 'Settings' submenu of plugins menu and will call this function when user chooses it.
  110. // You can display settings dialog, and do whatever you want.
  111. extern OSStatus VisSettings(WindowPtr inWindow, UInt32* ioRefcon);
  112.  
  113. // These functions are called when track in MacAMP is started or stopped. You can clear draw area
  114. // etc here. Note that you can also use ma->GetStatus callback to get the current status.
  115. extern OSStatus VisTrackBegin(WindowPtr inWindow, UInt32* ioRefcon);
  116. extern OSStatus VisTrackEnd(WindowPtr inWindow, UInt32* ioRefcon);
  117.  
  118. /************************************************************
  119.                     TYPEDEFS AND STRUCTS
  120. ************************************************************/
  121. // •Plugin callbacks
  122. typedef OSStatus    (*visInitProcPtr)(FSSpecPtr, WindowPtr*, UInt32*);
  123. typedef OSStatus    (*visGenericProcPtr)(WindowPtr, UInt32*);
  124. typedef OSStatus    (*visClickProcPtr)(WindowPtr, Point, UInt32*);
  125. typedef OSStatus    (*visEventProcPtr)(WindowPtr, EventRecord*, UInt32*);
  126. typedef Boolean     (*visErrorProcPtr)(StringPtr, OSStatus*);
  127.  
  128. // •MacAMP Callbacks
  129. //  You can call these anytime you want.
  130.  
  131. typedef void        (*maVisGetValuesArray)(UInt8** outArray, UInt16* outArraySize);
  132. // Get an array of pre-computed values for frequences.
  133. // Every value represents one frequency, and can be in range #0-232.
  134. // Input:
  135. //        none
  136. //    Output:
  137. //        outArray        = pointer to values array
  138. //        outArraySize    = size of the array
  139. //    Returns:
  140. //        nothing
  141.  
  142. typedef void        (*maVisGetFFTArray)(double** outFFT, UInt16* outFFTSize);
  143. // Get FFT array. First half of the array are real parts, second - imaginary.
  144. // Input:
  145. //        none
  146. //    Output:
  147. //        outFFT            = pointer to raw fft array (or nil, if not available)
  148. //        outBufferSize    = size of the array
  149. //    Returns:
  150. //        nothing
  151.  
  152. typedef void        (*maVisGetSoundBuffer)(Ptr* outSoundBuffer, UInt16* outBufferSize);
  153. // Get current sound buffer.
  154. // Input:
  155. //        none
  156. //    Output:
  157. //        outSoundBuffer    = pointer to sound buffer being played (or nil, if no track is playing)
  158. //        outBufferSize    = size of the buffer, in bytes
  159. //    Returns:
  160. //        nothing
  161.  
  162. typedef void        (*maVisGetStatus)(UInt32* outTimer, UInt32* outStatus);
  163. // Get status of thge player (timer, states of repeat, random, sleep etc).
  164. // Input:
  165. //        none
  166. //    Output:
  167. //        outTimer            = timer, in seconds
  168. //        outStatus            = flags field containing status* constants.
  169. //                                (for example, to check if Random mode is set, check for (outStatus & statusRandom))
  170. //    Returns:
  171. //        nothing
  172.  
  173. // Status codes
  174. enum {
  175.     statusRandom    = (1L << 0),
  176.     statusSleep        = (1L << 1),
  177.     statusRepeat    = (1L << 2),
  178.     statusRepeat1    = (1L << 3),
  179.     statusPlaying     = (1L << 4),
  180.     statusPaused    = (1L << 5),
  181.     statusStopped     = (1L << 6)
  182. };
  183.  
  184. typedef OSStatus    (*maVisGetTrackLocationProcPtr)(OSType* outType, Ptr* outData);
  185. // Get current track location.
  186. // Input:
  187. //        none
  188. //    Output:
  189. //        outType            = location type, either locationFile, locationURL or locationNone
  190. //        outData            = location data (depends on outType, see below)
  191. //    Returns:
  192. //        noErr            = lyrics information fetched.
  193. //        resNotFound        = no track is playing at the moment.
  194.  
  195. // Location types
  196. enum {
  197.     locationFile    = 'file',        // outData = FSSpecPtr
  198.     locationURL        = 'url ',        // outData = char* (C string)
  199.     locationNone    = 'none'        // outData = void, does not contains valid data
  200. };
  201.  
  202. typedef OSStatus    (*maVisGetID3InformationProcPtr)(StringPtr outArtist, StringPtr outTitle, StringPtr outAlbum, StringPtr outYear, Ptr* outLyrics);
  203. // Get current track ID3 information.
  204. // Input:
  205. //        none
  206. //    Output:
  207. //        outArtist        = artist
  208. //        outTitle        = title
  209. //        outAlbum        = album (if available, or nil)
  210. //        outYear            = year (if available, or nil)
  211. //        outLyrics        = lyrics (if available, or nil)
  212. //    Returns:
  213. //        noErr            = lyrics information fetched.
  214. //        resNotFound        = no track is playing at the moment.
  215.  
  216. typedef QDGlobalsPtr (*maVisGetQDPtrProcPtr)(void);
  217. // Return the pointer to QD globals (qd->...).
  218. // Input:
  219. //        none
  220. //    Output:
  221. //        none
  222. //    Returns:
  223. //        pointer to qd globals
  224.  
  225. typedef void (*maVisEnterFullScreen)(OSType inAuthorID, OSType inPluginID);
  226. // Notify MacAMP of your plugin entering full-screen mode.
  227. // After this call MacAMP hides all its windows, and suspends processing other visual plugins
  228. // to ensure maximum CPU time available for your plugin.
  229. // Input:
  230. //        inAuthorID        = author ID as defined in VisInfoBlock structure
  231. //        inPlugID        = plugin ID as defined in VisInfoBlock structure
  232. //    Output:
  233. //        none
  234. //    Returns:
  235. //        nothing
  236. //
  237. // Note: if you pass author/plugin IDs different than defined in your VisInfoBlock, that could cause
  238. // abnormal MacAMP behavior.
  239.  
  240. typedef void (*maVisExitFullScreen)(void);
  241. // Notify MacAMP of your plugin exiting full-screen mode.
  242. // All previously hidden windows will be shown again, and other visual plugins will get events.
  243. // Input:
  244. //        none
  245. //    Output:
  246. //        none
  247. //    Returns:
  248. //        nothing
  249.  
  250. typedef OSStatus (*maVisSavePrefs)(OSType inAuthorID, OSType inPluginID, Ptr inBuffer, UInt16 inSize);
  251. // Save plugin-specific preferences in MacAMP Data file located in System Folder.
  252. // Input:
  253. //        inAuthorID         = authorID of plugin
  254. //        inPluginID         = pluginID of plugin
  255. //        inBuffer        = pointer to buffer containing preferences chunk to be saved
  256. //        inSize            = size of buffer to be saved
  257. //    Output:
  258. //        none
  259. //    Returns:
  260. //        noErr            = preferences saved successfully.
  261. //        memFullErr        = an unknown, probably memory-related error has occurred.
  262.  
  263. typedef OSStatus (*maVisReadPrefs)(OSType inAuthorID, OSType inPluginID, Ptr inBuffer, UInt16* ioSize);
  264. // Read plugin-specific preferences you have saved before with SavePrefs hook.
  265. // Input:
  266. //        inAuthorID         = authorID of plugin
  267. //        inPluginID         = pluginID of plugin
  268. //        inBuffer        = pointer to pre-allocated buffer to store preferences
  269. //        ioSize            = size of allocated buffer
  270. //    Output:
  271. //        ioSize            = actual size of preferences
  272. //    Returns:
  273. //        noErr            = preferences read successfully.
  274. //        resNotFound        = unable to find such preferences chunk
  275. //        memFullErr        = size of preferences chunk exceeds size of allocated buffer
  276. //                            (ioSize contains size of preferences chunk)
  277.  
  278. // Various structures
  279. #pragma options align=power
  280.  
  281. // This is the structure for MacAMP callbacks.
  282. typedef struct {
  283.     maVisGetValuesArray                GetValues;
  284.     maVisGetFFTArray                GetFFT;
  285.     maVisGetStatus                    GetStatus;
  286.     maVisGetTrackLocationProcPtr    GetTrackLocation;
  287.     maVisGetID3InformationProcPtr    GetID3Information;
  288.     maVisGetQDPtrProcPtr            GetQDGlobals;
  289.     
  290.     // Full-screen mode
  291.     maVisEnterFullScreen            EnterFullScreen;
  292.     maVisExitFullScreen                ExitFullScreen;
  293.     
  294.     // Storing and reading prefs
  295.     maVisReadPrefs                    ReadPrefs;
  296.     maVisSavePrefs                    SavePrefs;
  297.  
  298.     // New for 1.01
  299.     maVisGetSoundBuffer                GetSoundBuffer;
  300. } VPCallbacks, *VPCallbacksPtr;
  301.  
  302. // Main structure for the plugin. Main entry point for the PEF fragment should point to
  303. // a global variable of this type.
  304. typedef struct {
  305.     UInt16    api;                    // API used. Should always contain VP_API_VERSION
  306.     OSType    type;                    // Plugin type. Should be plugVisual.
  307.     
  308.     OSType    authorID;                // Author ID should be registered with @soft to prevent
  309.                                     //  incompatibilities. mailto:devsupport@at-soft.net or
  310.                                     //  mailto:devsupport@macamp.com
  311.     OSType    pluginID;                // Plugin ID can be anything the author wishes. It is
  312.                                     //  used with author id to store plugin preferences etc
  313.     
  314.     UInt32    flags;                    // Plugin flags
  315.     
  316.     Str255    name;                    // Plugin name (displayed in Plugins menu)
  317.  
  318.     visInitProcPtr            initProc;
  319.     visGenericProcPtr        terminateProc;
  320.     visGenericProcPtr        idleProc;        // set to nil if you don't want to be called at idle time
  321.     visGenericProcPtr        aboutProc;
  322.  
  323.     visGenericProcPtr        drawProc;
  324.     visClickProcPtr            clickProc;
  325.     
  326.     visEventProcPtr            keyDownProc;    // set to nil if you don't want keydowns.
  327.     visEventProcPtr            macEventProc;    // set to nil if you don't want to handle update/click events manually.
  328.     
  329.     visErrorProcPtr            errorProc;
  330.     visGenericProcPtr        settingsProc;    // set to nil if you don't want to be displayed in settings submenu
  331.     visGenericProcPtr        trackBeginProc;
  332.     visGenericProcPtr        trackEndProc;
  333.     
  334.     // Set these to nil. They are reserved for future expansion.
  335.     visGenericProcPtr        reservedProc1;
  336.     visGenericProcPtr        reservedProc2;
  337.     visGenericProcPtr        reservedProc3;
  338.     visGenericProcPtr        reservedProc4;
  339.         
  340.     // Special APIs (Set to nil, MacAMP will set it to the right value)
  341.     VPCallbacksPtr                ma;
  342. } VPInfoBlock, *VPInfoPtr;
  343. #pragma options align=reset
  344.  
  345. #ifdef __cplusplus
  346. }
  347. #endif
  348.